home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat2 / standard / sysget.z / sysget
Encoding:
Text File  |  2001-04-17  |  8.5 KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSYYYYSSSSGGGGEEEETTTT((((2222))))                                                            SSSSYYYYSSSSGGGGEEEETTTT((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      sysget - Call for reading or writing kernel data
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      #include <sys/sysget.h>
  13.  
  14.      sysget (int name, char *buffer, int buflen, int flags,
  15.      sgt_cookie_t *cookie);
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      The sysget system call provides user access to kernel structures and
  19.      tables on IRIX systems. sysget can return data for a combination of cpus,
  20.      nodes, or cells depending on the combination of flags and cookie
  21.      settings.
  22.  
  23.      The sysget system call accepts the following arguments:
  24.  
  25.      name    Identifies the kernel structure or table. The sys/sysget.h file
  26.              contains the list of names supported. Most come from the sysmp
  27.              MP_SAGET options.  Here is a partial list:
  28.  
  29.              SGT_SINFO    SGT_MINFO SGT_DINFO SGT_SERR Returns the various
  30.                           sysinfo-type structures. See the sys/sysinfo.h file.
  31.  
  32.              SGT_RMINFO   Returns the rminfo structure. See the sys/sysmp.h
  33.                           file.
  34.  
  35.              SGT_NODE_INFO
  36.                           Returns the nodeinfo structure for each node. See
  37.                           the sys/sysinfo.h file.
  38.  
  39.              SGT_KSYM     Returns the structure identified by the kernel
  40.                           symbol specified in the cookie by using the
  41.                           SGT_COOKIE_SET_KSYM() macro. Only a subset of kernel
  42.                           symbols are supported. See the sys/sysget.h file.
  43.  
  44.      buffer  Points to the user's buffer space.
  45.  
  46.      buflen  Specifies the size of buffer in bytes.
  47.  
  48.      flags   Specifies option flags.  A user must select the SGT_INFO,
  49.              SGT_READ, or SGT_WRITE flag.  flags is combination of one or more
  50.              of the following:
  51.  
  52.              SGT_INFO     Returns information on the kernel structure or table
  53.                           defined by the name argument. This option is similar
  54.                           to the sysmp MP_SASZ option.  The buffer argument
  55.                           points to a structure defined in the sys/sysget.h
  56.                           file as the following:
  57.  
  58.                            struct sgt_info {
  59.                                  int      si_size;
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSYYYYSSSSGGGGEEEETTTT((((2222))))                                                            SSSSYYYYSSSSGGGGEEEETTTT((((2222))))
  71.  
  72.  
  73.  
  74.                                  int      si_num;
  75.                                  int      si_hiwater;
  76.                            }
  77.  
  78.              SGT_READ     Returns the information defined by the name argument
  79.                           in the buffer specified by the buffer argument.
  80.  
  81.              SGT_STAT     Returns information about the table or server
  82.                           specified by the name argument. This information is
  83.                           similar to that provided by the SGT_INFO flag.
  84.  
  85.              SGT_SUM      This flag is obsolete and will be ignored.
  86.  
  87.              SGT_WRITE    Writes the information specified by the buffer
  88.                           argument to the kernel structure defined by the name
  89.                           argument.
  90.  
  91.              SGT_CPUS     Returns data for each cpu. Not all structures
  92.                           support this option.
  93.  
  94.              SGT_NODES    Returns data for each node. Not all structures
  95.                           support this option.
  96.  
  97.      cookie  Specifies which cell, cpu, or node should be used when asking for
  98.              information.  The kernel also uses it as a place-holder mechanism
  99.              to allow sysget to be used iteratively to return a list of
  100.              structures when the length of the list is unknown. Other uses are
  101.              to specify a specific location to seek to in a list.
  102.  
  103.              This argument points to a structure defined as follows:
  104.  
  105.               struct sgt_cookie {
  106.                      sc_status_t    sc_status;
  107.                      union {
  108.                              cell_t          cellid;
  109.                              cnodeid_t       cnodeid;
  110.                              int             cpuid;
  111.                      } sc_id;
  112.                      sc_type_t       sc_type;
  113.                      char            sc_opaque[SGT_OPAQUE_SZ];
  114.               }
  115.  
  116.              The cookie must be initialized before the first call by using the
  117.              SGT_COOKIE_INIT() macro.  See the sys/sysget.h file
  118.  
  119. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  120.      If sysget completes normally, the number of bytes copied is returned,
  121.      otherwise a value of -1 is returned and errno is set to indicate the
  122.      error.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSYYYYSSSSGGGGEEEETTTT((((2222))))                                                            SSSSYYYYSSSSGGGGEEEETTTT((((2222))))
  137.  
  138.  
  139.  
  140. EEEERRRRRRRROOOORRRRSSSS
  141.      The sysget system call fails if one of the following error conditions
  142.      occurs:
  143.  
  144.      EEEErrrrrrrroooorrrr CCCCooooddddeeee          DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
  145.  
  146.      EFAULT              The buffer address specified is not valid.
  147.  
  148.      EINVAL              A flag was specified in a context that was not valid
  149.                          or the cookie was not set properly.
  150.  
  151.      ENOENT              The value specified in the name argument or in
  152.                          combination with the cookie is unknown.
  153.  
  154.      ENOTSUP             The function specified by the flags parameter is not
  155.                          supported.
  156.  
  157.      ESRCH               The cookie or cpu specified is not valid.
  158.  
  159. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  160.      The following examples show how to use the sysget system call to retrieve
  161.      information.
  162.  
  163.      Example 1:  This example shows how to use sysget to obtain the number and
  164.      size of sysinfo structures in the system (a system running cells will
  165.      have a sysinfo structure per cell):
  166.  
  167.         sgt_info_t info;
  168.         sgt_cookie_t cookie;
  169.  
  170.         SGT_COOKIE_INIT(&cookie);
  171.         sysget(SGT_SINFO, (char *)&info, sizeof(info),
  172.                 SGT_INFO, &cookie);
  173.         printf("number of sysinfo: %d, size: %d\n",
  174.                 info.si_num, info.si_size);
  175.  
  176.      Example 2:  In this example, sysget reads the list of sysinfo structures
  177.      for each cpu:
  178.  
  179.         sgt_info_t info;
  180.         sgt_cookie_t cookie;
  181.         struct sysinfo *si;
  182.  
  183.         SGT_COOKIE_INIT(&cookie);
  184.         sysget(SGT_SINFO, (char *)&info, sizeof(info),
  185.                 SGT_INFO | SGT_CPUS, &cookie);
  186.  
  187.         si = (struct sysinfo *)malloc(info.si_num * info.si_size);
  188.  
  189.         SGT_COOKIE_INIT(&cookie);
  190.         sysget(SGT_SINFO, (char *)si, info.si_num * info.si_size,
  191.                 SGT_READ | SGT_CPUS, &cookie);
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSYYYYSSSSGGGGEEEETTTT((((2222))))                                                            SSSSYYYYSSSSGGGGEEEETTTT((((2222))))
  203.  
  204.  
  205.  
  206.      Example 3:  In this example, sysget reads the list of sysinfo structures
  207.      for each cpu one at a time by iterating on the cookie:
  208.  
  209.         sgt_info_t info;
  210.         sgt_cookie_t cookie;
  211.         struct sysinfo si;
  212.  
  213.         SGT_COOKIE_INIT(&cookie);
  214.         while (cookie.sc_status != SC_DONE) {
  215.                sysget(SGT_SINFO, (char *)&si, sizeof(si),
  216.                    SGT_READ | SGT_CPUS, &cookie);
  217.         }
  218.  
  219.      Example 4:  This example shows how to use sysget to read the contents of
  220.      a structure by specifying its kernel symbol using the SGT_KSYM option:
  221.  
  222.         sgt_cookie_t cookie;
  223.         int avenrun[3];
  224.  
  225.         SGT_COOKIE_INIT(&cookie);
  226.         SGT_COOKIE_SET_KSYM(&cookie, "avenrun");
  227.         sysget(SGT_KSYM, (char *)avenrun, sizeof(avenrun),
  228.                 SGT_READ, &cookie);
  229.  
  230. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  231.      sysmp(2), syssgi(2), nlist(3C), sysctl(3C)
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.